<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>nmrglue.linesh &mdash; nmrglue v0.1 documentation</title>
    <link rel="stylesheet" href="../_static/sphinxdoc.css" type="text/css" />
    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '../',
        VERSION:     '0.1',
        COLLAPSE_MODINDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="../_static/jquery.js"></script>
    <script type="text/javascript" src="../_static/doctools.js"></script>
    <link rel="top" title="nmrglue v0.1 documentation" href="../index.html" />
    <link rel="up" title="Reference Guide" href="index.html" />
    <link rel="next" title="nmrglue.peakpick" href="peakpick.html" />
    <link rel="prev" title="nmrglue.leastsqbound" href="leastsqbound.html" /> 
  </head>
  <body>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="../genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="../modindex.html" title="Global Module Index"
             accesskey="M">modules</a> |</li>
        <li class="right" >
          <a href="peakpick.html" title="nmrglue.peakpick"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="leastsqbound.html" title="nmrglue.leastsqbound"
             accesskey="P">previous</a> |</li>
        <li><a href="../index.html">nmrglue v0.1 documentation</a> &raquo;</li>
          <li><a href="index.html" accesskey="U">Reference Guide</a> &raquo;</li> 
      </ul>
    </div>
      <div class="sphinxsidebar">
        <div class="sphinxsidebarwrapper">
            <h3><a href="../index.html">Table Of Contents</a></h3>
            <ul>
<li><a class="reference external" href="#">nmrglue.linesh</a><ul>
<li><a class="reference external" href="#high-level-functions">High-Level Functions</a></li>
<li><a class="reference external" href="#low-level-functions">Low-Level Functions</a></li>
</ul>
</li>
</ul>

            <h4>Previous topic</h4>
            <p class="topless"><a href="leastsqbound.html"
                                  title="previous chapter">nmrglue.leastsqbound</a></p>
            <h4>Next topic</h4>
            <p class="topless"><a href="peakpick.html"
                                  title="next chapter">nmrglue.peakpick</a></p>
            <h3>This Page</h3>
            <ul class="this-page-menu">
              <li><a href="../_sources/reference/linesh.txt"
                     rel="nofollow">Show Source</a></li>
            </ul>
          <div id="searchbox" style="display: none">
            <h3>Quick search</h3>
              <form class="search" action="../search.html" method="get">
                <input type="text" name="q" size="18" />
                <input type="submit" value="Go" />
                <input type="hidden" name="check_keywords" value="yes" />
                <input type="hidden" name="area" value="default" />
              </form>
              <p class="searchtip" style="font-size: 90%">
              Enter search terms or a module, class or function name.
              </p>
          </div>
          <script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body">
            
  <div class="section" id="module-nmrglue.analysis.linesh">
<h1>nmrglue.linesh<a class="headerlink" href="#module-nmrglue.analysis.linesh" title="Permalink to this headline">¶</a></h1>
<p>Functions for fitting and simulating arbitrary dimensional lineshapes commonly
found in NMR experiments</p>
<p>This module is imported as nmrglue.linesh and can be called as such</p>
<div class="section" id="high-level-functions">
<h2>High-Level Functions<a class="headerlink" href="#high-level-functions" title="Permalink to this headline">¶</a></h2>
<p>These are the functions the majority of users will use from the linesh module.</p>
<dl class="function">
<dt id="nmrglue.analysis.linesh.fit_spectrum">
<tt class="descclassname">nmrglue.analysis.linesh.</tt><tt class="descname">fit_spectrum</tt><big>(</big><em>spectrum</em>, <em>lineshapes</em>, <em>params</em>, <em>amps</em>, <em>bounds</em>, <em>ampbounds</em>, <em>centers</em>, <em>rIDs</em>, <em>box_width</em>, <em>error_flag</em>, <em>verb=True</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#nmrglue.analysis.linesh.fit_spectrum" title="Permalink to this definition">¶</a></dt>
<dd><p>Fit a spectrum by region which contain one or more peaks.</p>
<p>Parameters:</p>
<ul>
<li><p class="first">spectrum      Slicable spectral data.</p>
</li>
<li><dl class="first docutils">
<dt>lineshape     List of lineshapes by label (str) or a lineshape class.</dt>
<dd><p class="first last">See fit_NDregion for details.</p>
</dd>
</dl>
</li>
<li><dl class="first docutils">
<dt>params        P-length list (P is the number of peaks in region) of </dt>
<dd><p class="first last">N-length lists of tuples where each each tuple is the 
optimiztion starting parameters for a given peak and 
dimension lineshape.</p>
</dd>
</dl>
</li>
<li><p class="first">amps          P-length list of amplitudes.</p>
</li>
<li><dl class="first docutils">
<dt>bounds        List of bounds for parameter of same shape as params.  If</dt>
<dd><p class="first last">none of the parameters in a given dimension have limits 
None can be used, otherwise each dimension should have a 
list/tuple of (min,max) or None for each parameter.  
min or max may be None when there is no bound in a given 
direction.</p>
</dd>
</dl>
</li>
<li><dl class="first docutils">
<dt>ampbounds     P-length list of bounds for the amplitude with format </dt>
<dd><p class="first last">similar to bounds.</p>
</dd>
</dl>
</li>
<li><p class="first">centers       List of N-tuples indicating peak centers.</p>
</li>
<li><dl class="first docutils">
<dt>rIDs          P-length list of region numbers (peak with the same</dt>
<dd><p class="first last">region number are fit together).</p>
</dd>
</dl>
</li>
<li><dl class="first docutils">
<dt>box_width     N-tuple indicating box width to add and subtract from</dt>
<dd><p class="first last">peak centers to form region around peak to fit.</p>
</dd>
</dl>
</li>
<li><dl class="first docutils">
<dt>error_flag    Set to True to estimate errors for each lineshape</dt>
<dd><p class="first last">parameter and amplitude.</p>
</dd>
</dl>
</li>
<li><dl class="first docutils">
<dt>verb          Set to True to print summary of each region fit, False</dt>
<dd><p class="first last">supresses all printing.</p>
</dd>
</dl>
</li>
<li><dl class="first docutils">
<dt>kw            Additional keywords passed to the scipy.optimize.leastsq</dt>
<dd><p class="first last">function.</p>
</dd>
</dl>
</li>
</ul>
<dl class="docutils">
<dt>Returns: param_best,amp_best,iers if error_flag is False</dt>
<dd>param_best,amp_best,param_err,amp_err,iers if error_flag is True</dd>
</dl>
<ul>
<li><dl class="first docutils">
<dt>params_best   Optimal values for lineshape parameters with same format</dt>
<dd><p class="first last">as params input parameter.</p>
</dd>
</dl>
</li>
<li><p class="first">amp_best      List of optimal peak amplitudes.</p>
</li>
<li><dl class="first docutils">
<dt>param_err     Estimated lineshape parameter errors with same format</dt>
<dd><p class="first last">as oarans inout parameter. (Optional)</p>
</dd>
</dl>
</li>
<li><p class="first">amp_err       Estimated peak amplitude errors.</p>
</li>
<li><dl class="first docutils">
<dt>iers          List of interger flag from scipy.optimize.leastsq </dt>
<dd><p class="first last">indicating if the solution was found for a given peak.  
1,2,3,4 indicates that a solution was found. Other indicate
an error.</p>
</dd>
</dl>
</li>
</ul>
</dd></dl>

<dl class="function">
<dt id="nmrglue.analysis.linesh.fit_NDregion">
<tt class="descclassname">nmrglue.analysis.linesh.</tt><tt class="descname">fit_NDregion</tt><big>(</big><em>region</em>, <em>lineshapes</em>, <em>params</em>, <em>amps</em>, <em>bounds=None</em>, <em>ampbounds=None</em>, <em>wmask=None</em>, <em>error_flag=False</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#nmrglue.analysis.linesh.fit_NDregion" title="Permalink to this definition">¶</a></dt>
<dd><p>Fit a N-dimensional region.</p>
<p>Parameters:</p>
<ul>
<li><p class="first">region         N-dimensional region to fit.</p>
</li>
<li><p class="first">lineshapes     List of lineshapes by label (str) or a lineshape class.</p>
</li>
<li><dl class="first docutils">
<dt>params         P-length list (P is the number of peaks in region) of </dt>
<dd><p class="first last">N-length lists of tuples where each each tuple is the 
optimiztion starting parameters for a given peak and 
dimension lineshape.</p>
</dd>
</dl>
</li>
<li><p class="first">amps           P-length list of amplitudes.</p>
</li>
<li><dl class="first docutils">
<dt>bounds         List of bounds for parameter of same shape as params.  If</dt>
<dd><p class="first last">none of the parameters in a given dimension have limits 
None can be used, otherwise each dimension should have a 
list/tuple of (min,max) or None for each parameter.  
min or max may be None when there is no bound in a given 
direction.</p>
</dd>
</dl>
</li>
<li><dl class="first docutils">
<dt>ampbounds      P-length list of bounds for the amplitude with format </dt>
<dd><p class="first last">similar to bounds.</p>
</dd>
</dl>
</li>
<li><dl class="first docutils">
<dt>wmask          Array with same shape as region which is used to weight</dt>
<dd><p class="first last">points in the err calculation, typically a boolean array
is used to exclude certain points in the region.  Default
of None will include all points in the region equally
in the error calculation.</p>
</dd>
</dl>
</li>
<li><dl class="first docutils">
<dt>error_flag     Set to True to estimate errors for each lineshape </dt>
<dd><p class="first last">parameter and amplitude.</p>
</dd>
</dl>
</li>
<li><dl class="first docutils">
<dt>kw             Additional keywords passed to the scipy.optimize.leastsq </dt>
<dd><p class="first last">function.</p>
</dd>
</dl>
</li>
</ul>
<dl class="docutils">
<dt>Returns: param_best,amp_best,ier if error_flag is False</dt>
<dd>param_best,amp_best,param_err,amp_err,ier if error_flag is True</dd>
</dl>
<ul>
<li><dl class="first docutils">
<dt>params_best   Optimal values for lineshape parameters with same format</dt>
<dd><p class="first last">as params input parameter.</p>
</dd>
</dl>
</li>
<li><p class="first">amp_best      List of optimal peak amplitudes.</p>
</li>
<li><dl class="first docutils">
<dt>param_err     Estimated lineshape parameter errors with same format</dt>
<dd><p class="first last">as oarans inout parameter. (Optional)</p>
</dd>
</dl>
</li>
<li><p class="first">amp_err       Estimated peak amplitude errors.</p>
</li>
<li><dl class="first docutils">
<dt>ier           Interger flag from scipy.optimize.leastsq indicating if</dt>
<dd><p class="first last">the solution was found.  1,2,3,4 indicates that a solution
was found.  Otherwise the solution was not found.</p>
</dd>
</dl>
</li>
</ul>
<p>Note on the lineshape parameter:</p>
<p>Elements of the lineshape parameter list can be string indicating the
lineshape of given dimension or an instance of a lineshape class 
which provide a sim method which takes two arguments, the first being the 
length of the lineshape the second being a list of lineshape parameters, 
and returns a simulated lineshape as well as a nparam method which when 
given the length of lineshape returns the number of parameters needed to
describe the lineshape. Currently the following strings are allowed:</p>
<ul class="simple">
<li>&#8216;g&#8217; or &#8216;gauss&#8217;    Gaussian (normal) lineshape.</li>
<li>&#8216;l&#8217; or &#8216;lorentz&#8217;  Lorentzian lineshape.</li>
<li>&#8216;s&#8217; or &#8216;scale&#8217;    Scaled lineshape.</li>
<li>&#8216;p&#8217; or &#8216;peak&#8217;     Gaussian lineshape which takes FWHM as a parameter.</li>
</ul>
<p>The following are all valid lineshapes parameters for a 2D Gaussian peak:</p>
<p>[&#8216;g&#8217;,&#8217;g&#8217;]
[&#8216;gauss&#8217;,&#8217;gauss&#8217;]
[ng.analysisbase.gauss1D(),ng.analysisbase.gauss1D()]</p>
<p>An simple example of a lineshape class which simulates the function y=c:
XXX</p>
</dd></dl>

<dl class="function">
<dt id="nmrglue.analysis.linesh.sim_NDregion">
<tt class="descclassname">nmrglue.analysis.linesh.</tt><tt class="descname">sim_NDregion</tt><big>(</big><em>shape</em>, <em>lineshapes</em>, <em>params</em>, <em>amps</em><big>)</big><a class="headerlink" href="#nmrglue.analysis.linesh.sim_NDregion" title="Permalink to this definition">¶</a></dt>
<dd><p>Simulate a arbitrary dimensional region with one or more peaks.</p>
<p>Parameters:</p>
<ul>
<li><p class="first">shape         tuple of region shape</p>
</li>
<li><dl class="first docutils">
<dt>lineshapes    List of lineshapes by label (str) or a lineshape class.</dt>
<dd><p class="first last">See fit_NDregion for additional documentation.</p>
</dd>
</dl>
</li>
<li><dl class="first docutils">
<dt>params        P-length list (P is the number of peaks in region) of </dt>
<dd><p class="first last">N-length lists of tuples where each each tuple is 
lineshape parameters for a given peak and dimension.</p>
</dd>
</dl>
</li>
<li><p class="first">amps          P-length of peak amplitudes.</p>
</li>
</ul>
<p>Returns: array containing simulated region</p>
</dd></dl>

<dl class="function">
<dt id="nmrglue.analysis.linesh.add_to_table">
<tt class="descclassname">nmrglue.analysis.linesh.</tt><tt class="descname">add_to_table</tt><big>(</big><em>rec</em>, <em>columns</em>, <em>column_names</em><big>)</big><a class="headerlink" href="#nmrglue.analysis.linesh.add_to_table" title="Permalink to this definition">¶</a></dt>
<dd><p>Add (append) multiple columns to a record array</p>
<p>Parameters:</p>
<ul class="simple">
<li>rec           Records array (table).</li>
<li>columns       List of columns data to append to table.</li>
<li>column_names  List of names of columns.</li>
</ul>
<p>Returns: rec (Records array with columns added)</p>
</dd></dl>

<dl class="function">
<dt id="nmrglue.analysis.linesh.pack_table">
<tt class="descclassname">nmrglue.analysis.linesh.</tt><tt class="descname">pack_table</tt><big>(</big><em>pbest</em>, <em>abest</em>, <em>iers</em>, <em>rec</em>, <em>param_columns</em>, <em>amp_column</em>, <em>ier_column=None</em><big>)</big><a class="headerlink" href="#nmrglue.analysis.linesh.pack_table" title="Permalink to this definition">¶</a></dt>
<dd><p>Pack fitting parameters into table</p>
<p>Parameters:</p>
<ul class="simple">
<li>pbest         List of best-fit parameters.  See fit_NDregion for format.</li>
<li>abest         List of best-fit amplitudes.</li>
<li>iers          List of fitting error return values.</li>
<li>rec           Records array (table) to save fitting parameters into.</li>
<li>param_columns List of parameter columns in rec. (format same as pbest)</li>
<li>amp_columns   Name of amplitude column in rec.</li>
<li>ier_column    Name of column in rec to save iers to, None to not save.</li>
</ul>
<p>Return nothing, rec is updated in place.</p>
</dd></dl>

<dl class="function">
<dt id="nmrglue.analysis.linesh.unpack_table">
<tt class="descclassname">nmrglue.analysis.linesh.</tt><tt class="descname">unpack_table</tt><big>(</big><em>rec</em>, <em>param_columns</em>, <em>amp_column</em><big>)</big><a class="headerlink" href="#nmrglue.analysis.linesh.unpack_table" title="Permalink to this definition">¶</a></dt>
<dd><p>Unpack initial fitting parameters from a table</p>
<p>Parameters:</p>
<ul>
<li><p class="first">rec           Records array (table) holding parameters.</p>
</li>
<li><dl class="first docutils">
<dt>param_columns List of column names which hold lineshape parameters.  </dt>
<dd><p class="first last">See fit_NDregion for format.</p>
</dd>
</dl>
</li>
<li><p class="first">amp_column    Name of columns in rec holding initial amplitudes.</p>
</li>
</ul>
<p>Returns: params,amps</p>
</dd></dl>

<dl class="function">
<dt id="nmrglue.analysis.linesh.estimate_scales">
<tt class="descclassname">nmrglue.analysis.linesh.</tt><tt class="descname">estimate_scales</tt><big>(</big><em>spectrum</em>, <em>centers</em>, <em>box_width</em>, <em>scale_axis=0</em><big>)</big><a class="headerlink" href="#nmrglue.analysis.linesh.estimate_scales" title="Permalink to this definition">¶</a></dt>
<dd><p>Estimate scale parameter for peaks in a spectrum</p>
<p>Parameters:</p>
<ul>
<li><p class="first">spectrum      Slicable spectral data.</p>
</li>
<li><p class="first">centers       List of N-tuples indicating peak centers.</p>
</li>
<li><dl class="first docutils">
<dt>box_width     N-tuple indicating box width to add and subtract from</dt>
<dd><p class="first last">peak centers to form region around peak to fit.</p>
</dd>
</dl>
</li>
<li><p class="first">scale_axis    Axis number to estimate scale parameters for.</p>
</li>
</ul>
</dd></dl>

</div>
<div class="section" id="low-level-functions">
<h2>Low-Level Functions<a class="headerlink" href="#low-level-functions" title="Permalink to this headline">¶</a></h2>
<p>These functions are typically not used directly by users. They are called by
high level functions.  Developers and user who want fine control over lineshape
fitting may be interested in these functions.</p>
<dl class="function">
<dt id="nmrglue.analysis.linesh.f_NDregion">
<tt class="descclassname">nmrglue.analysis.linesh.</tt><tt class="descname">f_NDregion</tt><big>(</big><em>region</em>, <em>ls_classes</em>, <em>p0</em>, <em>p_bounds</em>, <em>n_peaks</em>, <em>wmask</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#nmrglue.analysis.linesh.f_NDregion" title="Permalink to this definition">¶</a></dt>
<dd><p>Fit an arbitrary dimensional regions  containing one or more peaks 
using a contrained Levenberg-Marquard optmization algorithm.</p>
<p>Parameters:</p>
<ul class="simple">
<li>region        N-dimensional region to fit</li>
<li>ls_classes    List of lineshape classes</li>
<li>p0            Initial parameter guesses</li>
<li>p_bounds      (min,max) pairs for each element of p0</li>
<li>n_peaks       Number of peaks</li>
</ul>
<p>Additional keyword are passed directly to leastsqbound and in turn
passed to scipy.optimize.leastsq after variable transformation.</p>
</dd></dl>

<dl class="function">
<dt id="nmrglue.analysis.linesh.s_NDregion">
<tt class="descclassname">nmrglue.analysis.linesh.</tt><tt class="descname">s_NDregion</tt><big>(</big><em>p</em>, <em>shape</em>, <em>ls_classes</em>, <em>n_peaks</em><big>)</big><a class="headerlink" href="#nmrglue.analysis.linesh.s_NDregion" title="Permalink to this definition">¶</a></dt>
<dd><p>Simulate a arbitrary dimensional region with one or more peaks.</p>
<p>Parameters:</p>
<ul class="simple">
<li>p             List (and must be a list) of parameters</li>
<li>shape         tuple of region shape</li>
<li>ls_classes    List of lineshape classes</li>
<li>n_peaks       Number of peaks in region</li>
</ul>
<p>p is modified by this functions, pass a copy if p should be retained.</p>
</dd></dl>

<dl class="function">
<dt id="nmrglue.analysis.linesh.s_single_NDregion">
<tt class="descclassname">nmrglue.analysis.linesh.</tt><tt class="descname">s_single_NDregion</tt><big>(</big><em>p</em>, <em>shape</em>, <em>ls_classes</em><big>)</big><a class="headerlink" href="#nmrglue.analysis.linesh.s_single_NDregion" title="Permalink to this definition">¶</a></dt>
<dd><p>Simulate a arbitrary dimensional region with a single peak. Called 
repeatly by s_NDregion to build up a full ND region.</p>
<p>Parameters:
* p             List (and must be a list) of parameters
* shape         tuple of region shape
* ls_classes    List of lineshape classes</p>
</dd></dl>

<dl class="function">
<dt id="nmrglue.analysis.linesh.err_NDregion">
<tt class="descclassname">nmrglue.analysis.linesh.</tt><tt class="descname">err_NDregion</tt><big>(</big><em>p</em>, <em>region</em>, <em>shape</em>, <em>ls_classes</em>, <em>n_peaks</em>, <em>wmask</em><big>)</big><a class="headerlink" href="#nmrglue.analysis.linesh.err_NDregion" title="Permalink to this definition">¶</a></dt>
<dd>Error functions for a NDregion, called by f_NDregion function</dd></dl>

<dl class="function">
<dt id="nmrglue.analysis.linesh.make_slist">
<tt class="descclassname">nmrglue.analysis.linesh.</tt><tt class="descname">make_slist</tt><big>(</big><em>l</em>, <em>t_sizes</em><big>)</big><a class="headerlink" href="#nmrglue.analysis.linesh.make_slist" title="Permalink to this definition">¶</a></dt>
<dd><p>Create a list of tuples of given sizes from a list</p>
<p>Parameters:</p>
<ul class="simple">
<li>l         List/array to pack into shaped list.</li>
<li>t_sizes   List of tuple sizes.</li>
</ul>
</dd></dl>

<dl class="function">
<dt id="nmrglue.analysis.linesh.split_list">
<tt class="descclassname">nmrglue.analysis.linesh.</tt><tt class="descname">split_list</tt><big>(</big><em>l</em>, <em>N</em><big>)</big><a class="headerlink" href="#nmrglue.analysis.linesh.split_list" title="Permalink to this definition">¶</a></dt>
<dd>Split list l into N sublists of equal size</dd></dl>

</div>
</div>


          </div>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="../genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="../modindex.html" title="Global Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="peakpick.html" title="nmrglue.peakpick"
             >next</a> |</li>
        <li class="right" >
          <a href="leastsqbound.html" title="nmrglue.leastsqbound"
             >previous</a> |</li>
        <li><a href="../index.html">nmrglue v0.1 documentation</a> &raquo;</li>
          <li><a href="index.html" >Reference Guide</a> &raquo;</li> 
      </ul>
    </div>
    <div class="footer">
      &copy; Copyright 2010, Jonathan J. Helmus.
      Last updated on Apr 04, 2011.
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.4.
    </div>
  </body>
</html>